\name{corplot}
\alias{corplot}
\title{Plot a Correlation Matrix}
\description{Creates a tile plot of a correlation matrix using with colors indication strength of the correlation.}
\usage{
corplot(x, coverage, points = TRUE, digits = 2, plot = TRUE, ..., control.grobs)
}
\arguments{
  \item{x}{A correlation matrix}
  \item{coverage}{Optional.  A matrix with the same dimensions as the correlation matrix passed to \code{x} indicating the percentage of data present for each cell in the correlation matrix.  It is used to create a bubble plot on top of the tiles.}
  \item{points}{Logical.  Should a bubble plot (using points) be added to the tile plot?  If \code{FALSE}, text is added with the actual correlation values.}
  \item{digits}{The number of digits to use for rounding the correlation values text.}
  \item{plot}{Logical indicating whether or not to print the graph.  If \code{FALSE}, invisibly returns the grob.}
  \item{\dots}{Further arguments passed down.}
  \item{control.grobs}{Experimentally implemented.  Allows fine control of the plot and aesthetics, if desired.  However, there is no error checking so it would be easy to create invalid statements.}
}
\details{The actual plot is created using \code{ggplot2} and \code{geom_tile}.  In addition to creating the plot, the variables are ordered based on a hierarchical clustering of the correlation matrix.  Specifically, \code{1 - x} is used as the distance matrix.}
\value{
Primarily called for the side effect of creating a plot.  However, the \code{ggplot2} plot object is invisibly returned, so it can be saved, replotted, edited, etc.
}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}

\examples{
## example plotting the correlation matrix from the
## mtcars dataset
corplot(cor(mtcars))

dat <- as.matrix(iris[, 1:4])

## randomly set 25% of the data to missing
set.seed(10)
dat[sample(length(dat), length(dat) * .25)] <- NA

## create a summary of the data (including coverage matrix)
sdat <- SEMSummary(~ ., data = dat)
## using the plot method for SEMSummary (which basically just calls corplot)
plot(sdat)

## use the control.grobs argument to adjust the coverage scaling
## to go from 0 to 1 rather than the range of coverage
corplot(x = sdat$sSigma, coverage = sdat$coverage,
  control.grobs = list(area = quote(scale_area(limits = c(0, 1))))
)

## also works with plot() on a SEMSummary
plot(sdat, control.grobs = list(area = quote(scale_area(limits = c(0, 1)))))

rm(dat, sdat)
}
\keyword{hplot}
